home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 071-080 / amok73 / ums / doc / ums-cfg.doc < prev    next >
Text File  |  1993-11-04  |  11KB  |  340 lines
  1.  
  2.   UMS Message Format $VER: 9.1 (16.7.92)
  3.  
  4.   This text is (C) 1992 by Martin Horneffer.
  5.  
  6.   It  may  freely be copied and distributed, as long the the
  7. text is unchanged and this copyright notice is left intact.
  8.  
  9.  
  10.  
  11.  
  12.     The Universal Message System universal configuration
  13.  
  14.  
  15.  
  16. The UMS Message Base Processor (referred to as 'MBP') parses
  17. a global configuration file and provides possibility for all
  18. related  programs  to get their configuration from this file
  19. (through ums.library).
  20.  
  21. This file usually is named "ENVARC:ums.config" on an Amiga.
  22.  
  23. The   resulting   data   structures   are  called  the  "UMS
  24. configuration"
  25.  
  26.  
  27.  
  28.         I) Configuration Objects
  29.  
  30. The  UMS  configuration contains several objects.  There are
  31. four  main  types  of objects:  akas, netgroups, strings and
  32. users.
  33.  
  34.  
  35.         1) AKAs
  36.  
  37. AKAs  simply  are  a  list  of  strings,  where  each string
  38. describes  one  net-address  the  local  system is known as.
  39. AKAs are necessary to detect whether an incoming message has
  40. reached  its  destination,  or  whether  it  still has to be
  41. routed to another system.
  42.  
  43. An AKA in the config-file is defined by a line of the
  44. following form:
  45.  
  46. "AKA" <address>
  47.  
  48. Examples:
  49.  
  50.     aka Martin_Horneffer@mowgli.fido.de
  51.     AKA   2:242/7.9@Fidonet
  52.  
  53. Any  number  of such lines may be used.  The strings are not
  54. case-sensitive.
  55.  
  56.  
  57.         2) NETGROUPS
  58.  
  59. Since  more  and  more  networks  with different formats are
  60. interconnected  by  more  and  more  gateways, more and more
  61. newsgroups  are  available  through different networks under
  62. different names.  Thus it's necessary to know what different
  63. names all stand for the same newsgroup.
  64.  
  65. Two  groupnames  can  be declared to be the same netgroup by
  66. using a line of the following format:
  67.  
  68. "GROUP" <group1> = <group2>
  69.  
  70. Any  number  of  such  lines  may  be  used.   Any number of
  71. groupnames  may  be  declared to be identical.  If there are
  72. more  than  two names for the same group, more than one line
  73. will be needed.
  74.  
  75. Examples:
  76.  
  77.     group net1.a = net2.b
  78.     group net3.c = net4.d
  79.     group foo.bar = bla.fasel
  80.     group net1.a = net4.d
  81.  
  82. Now "net1.a", "net2.b", "net3.c" and "net4.d" are identical,
  83. but different to "foo.bar" and "bla.fasel".
  84.  
  85. Again, case is preserved, but not used for comparisons.
  86.  
  87.  
  88.         3) STRINGS
  89.  
  90. An   UMS   'config-string'   is  a  null-terminated  string,
  91. identified by an unique name.
  92.  
  93. They provide the most flexible possibility to provide custom
  94. configuration information.  Every UMS-related program should
  95. get its configuration from strings in the UMS configuration.
  96.  
  97. There  is  no  restriction  to  the  contents of the string,
  98. except that it needs to be null-terminated.
  99.  
  100. The  names  of  strings  are  case-insensitive.  In order to
  101. distinguish strings for different UMS applications and avoid
  102. collision   of   names,   every  name  must  consist  of  an
  103. application-specific  ID  followed  by  a dot and a suitable
  104. name.   String-names  without a dot are reserved for the MBP
  105. itself.
  106.  
  107. They are specified like this:
  108.  
  109. <name> = <string>
  110.  
  111. If <string> contains any control-chars or has whitespaces at
  112. its   beginning   or   end,  it  needs  to  be  enclosed  in
  113. double-quotes.    When   it's   in  double-quotes,  control-
  114. characters  are  escaped  with  "*"  in  a style similiar to
  115. AmigaDOS:
  116.  
  117. "*""   -> "
  118. "**"   -> *
  119. "*Xab" -> (0xab)
  120. "*R"   -> CR (0x0d)
  121. "*N"   -> LF (0x0a)
  122. "*E"   -> ESC (0x1b)
  123. (etc..)
  124.  
  125. Examples:
  126.  
  127.     foo.bar = blas-fasel
  128.     Fido.Origin = "Some stupid gag."
  129.     Newsreader.Bold = "*e[1m"
  130.  
  131.  
  132.         4) USERS
  133.  
  134. Defining  users  is  very  essential  to  the UMS MBP.  User
  135. definitions  tells  the  MBP  about the users it has to keep
  136. specific  data  for  and  the  access-rights  granted to the
  137. different users, etc.
  138.  
  139. There  are  two  main  types  of  users:   'real'  users and
  140. im-/exporters.   Actually,  there is also a third type:  the
  141. sysop,  which  is  much  like  a  'real'  user  but has some
  142. additional access-rights.
  143.  
  144. A  real  user  or sysop is usually associated with a natural
  145. person  who wants to use the MB.  An im-/exporter is treated
  146. much  the same way, but refers to a link to another message-
  147. processing  system,  eg a mailbox or a news-server.  Thus, a
  148. minimum  UMS  system  consists  of  at  least one sysop, who
  149. maintains  the  system,  reads  and writes messages, and one
  150. im-/exporter, which connects the UMS system with the rest of
  151. the world.
  152.  
  153. A user definition consists of several strings:
  154.  
  155.   NAME -
  156. the  (real)  name of the user.  For im-/exporters preferably
  157. the name of the remote system.
  158.  
  159.   ALIAS -
  160. every  user can have a random number of aliases.  A user may
  161. always  be  addressed  by  its  name  or one of its aliases.
  162. Thus,  no  alias of one user may be equal to a name or alias
  163. of any other user within the same system.
  164.  
  165.   SYSOP -
  166. this is a boolean flag that makes a simple user be sysop.
  167.  
  168.   PASSWORD -
  169. a password needed for logins.
  170.  
  171.   PRIORITY -
  172. an integer between -100 and +100.  Currently not very
  173. important.
  174.  
  175.   READACCESS -
  176. an  AmigaDOS  style  pattern, that tells the MBP what public
  177. messages  a  user  is  allowed to read.  A user may read all
  178. public  messages that's group matches the user's READACCESS-
  179. pattern.
  180.  
  181.   WRITEACCESS -
  182. a  pattern  that  defines  the group a user may write public
  183. messages  to.   In  order  to  be  allowed to write a public
  184. message to the MB, the message's group must match the user's
  185. WRITEACCESS-pattern
  186.  
  187.   NETACCESS  -
  188. a  pattern  that  defines  what  addresses  a user may write
  189. private  messages  to.  The ToPath-field of the message must
  190. match this pattern.
  191.  
  192.   EXPORT -
  193. when this is specified, the user will be an im-/exporter and
  194. no  'real'  user  or  sysop.   The EXPORT-pattern says which
  195. private  messages are exported by an exporter.  All messages
  196. that's  ToPath  matches  an exporter's EXPORT-pattern may be
  197. exported by that exporter.  An exporter must inspect all the
  198. private  messages it can read and tell the MBP, whether they
  199. actually could be exported or not.
  200.  
  201.   IMPORT -
  202. a  pattern  a  message's  FromPath must match to in order to
  203. allow the message to be written to the MB.
  204.  
  205.   DISTRIBUTION -
  206. only  for exporters.  When a message (public or private) has
  207. a   distribution-field,   it   must   match   the  exporters
  208. DISTRIBUTION-pattern   in  order  to  be  readable  to  that
  209. exporter.
  210.  
  211.  
  212. The  definition  of an user in the UMS configuration file is
  213. started  with  the  single  keyword  "user"  in  a  line and
  214. completed with the single "enduser".
  215.  
  216.  
  217. Every user may have 'local' strings.  These are exactly like
  218. the  global  config-strings  and  defined  in  the same way,
  219. except  that  they  need  to be between "user" and "enduser"
  220. lines.   Local  config-strings  with the same name as global
  221. config-strings usually supersede the global ones.
  222.  
  223. Special strings for the user-definition are defined similiar
  224. to string-definitions, except of 'SYSOP' having no value and
  225. 'ALIAS', which may occur as often as desired.
  226.  
  227. Examples:
  228.  
  229.     user
  230.       name         = "Martin Horneffer"
  231.       password        = secret
  232.       readaccess   = #?
  233.       writeaccess  = #?
  234.       netaccess    = #?
  235.       sysop
  236.       alias        = SYSOP
  237.       alias        = Martin_Horneffer
  238.       alias        = "Sysop Martin Horneffer"
  239.       alias        = mh
  240.       alias        = maho
  241.     enduser
  242.  
  243.     user
  244.       name         = "Test User"
  245.       password     = guest
  246.       readaccess   = fido.#?
  247.       writeaccess  = "~(#?sysop#?)
  248.       netaccess    = "#?@Fidonet"
  249.       alias        = test
  250.       alias        = guest
  251.     enduser
  252.  
  253.     user
  254.       name         = FidoBoss
  255.       readaccess   = fidonet.#?
  256.       priority     = -20
  257.       writeaccess  = #?
  258.       import       = #?
  259.       export       = "#?(@Fidonet|.de|.ca|.ch|.at|.org|.com|.edu|.mil)"
  260.       distribution = "(%|#?,)(mowgli|fidonet|world)(,#?|%)"
  261.     enduser
  262.  
  263.  
  264.  
  265.         II) Special config strings
  266.  
  267. The  MBP  itself  needs  some  global config strings for its
  268. configuration.   They  differ  from custom config strings by
  269. not having a dot (".") in their name.
  270.  
  271.   DOMAIN-ADDRESS -
  272. this  must  be  a unique domain-style address, which is used
  273. for creation of message IDs.  The MBP creates message-IDs by
  274. using  a  serial  decimal  number and appending an "at-sign"
  275. ("@") in front of the domain-address.
  276.  
  277.   MBPATH -
  278. pathname  of  the  directory where the MBP should create the
  279. message base.  Should end with ":" or "/".
  280.  
  281.   LOGFILE -
  282. name  of  the logfile, where the MBP will report actions and
  283. errors  to.  UMS applications may (and should) also use this
  284. logfile  (via  ums.library).   The  user  should  read  this
  285. logfile regularly in order to detect all possible errors.
  286.  
  287.   LOGLEVEL -
  288. an number from 1 to 9 that indicates how many entries should
  289. be written to the logfile.  Sould be at least 5, recommended
  290. is 6 or 7.
  291.  
  292.   HEADERFIELDS -
  293. a  list  of  numbers,  separated  by commas.  Indicates what
  294. text-fields    of    an    UMS    message   are   considered
  295. "header"-fields.  These fields are stored in the header-file
  296. instead  of  the  text-file  and thus can be read or scanned
  297. faster.   Also  only  header-fields fields can have indices.
  298. Recommended is "1,2,3,4,5,6,7,8,9,10,11,13,14,16,17".
  299.  
  300.   INDEXFIELDS -
  301. a list of numbers, like HEADERFIELDS.  Indicates what fields
  302. the  MBP  should  keep  an  index  on.  Every index requires
  303. additional  space,  both on storage as well as on memory but
  304. allows  some  actions  (selecting,  searching messages) that
  305. otherwise are not possible with that fields.  Recommended is
  306. "1,3,5,8,9,10".
  307.  
  308.   FLUSHINTERVAL -
  309. the MBP updates the message base every time an user logs out
  310. and  after  a given time.  FLUSHINTERVAL specifies this time
  311. in seconds.
  312.  
  313.   HDRFILL -
  314.   TXTFILL -
  315. in  some special cases it is necessary for the MBP to change
  316. existing  message.  In order to allow the changed message to
  317. be  larger  than the old one, some bytes need to be reserved
  318. at creation of the message.  HDRFILL and TXTFILL specify the
  319. number  of  bytes that are to be reserved in the header- and
  320. text-file.  The recommended value is "80".
  321.  
  322.   HDRWRITEBUF -
  323.   TXTWRITEBUF -
  324. size  of write-buffers in bytes.  The larger the buffer, the
  325. fewer  writes  must  be  done  to  the storage.  Large write
  326. buffers make large imports faster.
  327.  
  328.   HDRREADBUF -
  329.   TXTREADBUF -
  330. size  of read-buffers in bytes.  The values for best overall
  331. performance mainly depend on the ratio seek/transfer-speed.
  332.   If  you  have  enough  memory  you  could  consider making
  333. HDRREADBUF as large as maximum size of the header-file.
  334.  
  335.   CLEANBUF -
  336. size   of   the   buffer  to  be  used  on  cleanup  of  the
  337. messagebase.
  338.  
  339. For examples see the example configuration file.
  340.